ShareWare OnLine 2/ShareWare OnLine Volume 2 (CMS Software)(1993).iso/elecmail/ozt11b.zip/OZT.DOC

Text File | 1993-04-01 | 18KB | 433 lines

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- overview

OZT is a rethreader for OzCIS forum message files. When messages from multiple
passes are stored in the same file, they will be in thread order only within
each group. Each group starts with its own "dummy" message generated by OzCIS.
This is called the forum pass header. OZT will take such a file, remove all
forum pass headers, and duplicate messages, and reorganize the remainder into
strict thread order based on message number.

OZT is designed to be simple to use, and to perform only the basic job without
a lot of frills. There are two main reasons for this:

   a> my own needs for this are pretty simple
   b> OzCIS v2 will have full-fledged interactive thread handling capabilities
      - no sense writing something that would soon be made obsolete


-- what's new in 1.1a(b)

I added the features mentioned in the "planned enhancements" category from 1.1:

   redirectable output
   sets errorlevel on exit
   write caching

Also new:

   debug lists command line option
   blank line between sections in summary list
   original file is renumbered rather than output file
b  will now remove a Ctrl-Z end-of-file marker from the input file if found
b  widened "level" column in thread table output
b  fixed bug : stack overflow (RTE 202) with heavily nested threads


   -- redirectable output

Now all screen output can be sent into a file for later viewing. This could be
useful to capture the output of several OZT sessions in a batch file and view
them at the end of the batch run:

   ozt bor\bpascal over kill tables > ozt.out
   ozt ibmcom\ibmcom over kill tables >> ozt.out
   list ozt.out

Or it could be used to keep a log of all OZT runs, or to simply send the output
to the bit-bucket:

   ozt > nul


   -- sets errorlevel on exit

This feature would also be used in batch files. If the program runs
succesfully, or the help screen is displayed (by running with no parameters),
the errorlevel is 0. If the program terminates prematurely for any other
reason, the errorlevel is 1. Perhaps in the future I will assign different
error levels to the different errors that can occur, but for now I'll just
leave it at "yes" or "no".


_66

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- what's new...
   -- write caching

I included this feature in hopes of reducing the disk-thrashing that occurs
when writing the final output file. The previous version would read then write
every single message individually. This version will read as many messages as
possible from the input file into a buffer, and then write the entire buffer.
There is still a fair amount of thrashing that goes on, but nowhere nearly as
much as before. There are even ways to improve this (keeping as much of the
file in memory as possible), but for now, this works.


   -- debug lists command line options

Since this program is still "wet behind the ears", I thought it prudent to
allow users to have access to all of the intermediary structures that are
generated during the process. Since there are more variations of message files
under the Sun than dreamed of in my meager philosophy (Todd-atio), having this
capability at hand will allow message reading problems to be pinpointed more
quickly. See "-- using debug lists" below for more info.


   -- blank line between sections in summary list

This is just a cosmetic thing, but it helps to break the list up a little bit.


   -- original file is renumbered rather than output file

In version 1.1, when not using the "over" command line switch, the new output
file would have a numbered extension. Versions 1.1a and above now apply the
renumbering to the original file, and leave the output file with the original
name. Confused yet? Imagine this session:

   ozt ibmcom\ibmcom

   OZT 1.1 produces                        OZT 1.1a & up produce

   ibmcom.mes - original file              ibmcom.001 - original file
   ibmcom.001 - rethreaded version         ibmcom.mes - rethreaded version

The idea behind this, is if you wanted to rethread the file, then read it, you
would have to rename *.001 to *.MES, using a temporary name in between. In
fact, this is exactly what the later versions do internally.


b  -- removes Ctrl-Z

When OZT starts, it looks at the very last byte of the input file. If this byte
is a Ctrl-Z (#26, end-of-file marker), it is overwritten by a space. This makes
it easier to merge files with the DOS COPY command. See "-- usage notes" below.


b  -- widened "level" column in thread table output

This column can now display up to 32 levels of nesting. The previous version
would be truncated after 11 levels. Lets see if any one can break this!




_132

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────
-- what's new...
b  -- stack overflow fixed

Previously, if a thread was encountered that 16 or more sequential replies, the
program would crash with a Runtime Error #202. To solve this, I simply doubled
the amount of stack space available to the program, from 16K up to 32K. We'll
have to see what the next barrier is. Anyone have any threads with more than 32
sequential replies?!


-- installation

OZT can be placed in any subdirectory in the path. The most logical place to
put it might be in your OzCIS subdirectory. OZT.EXE is self-contained and
doesn't use or create any data files or temporary files, unless the "debug"
option is used, in which case it creates LOST of output files. See below.


-- operation

OZT is a command-line utility. It reads in a file, processes it, and spits it
back out, with no user interaction. The command format is:

   OZT <message filename[.MES]> [over] [kill] [tables] [debug]

OZT will assume an extension of .MES if none is specified. There are three
optional parameters which have the following effects:

   over    overwrites the original file (otherwise, OZT will rename the
           original file by giving it a numbered extension)

   kill    deletes the .IXM file with the same name, causing OzCIS to reindex
           the file the next time it is loaded

   tables  writes thread table and thread summary files to the disk - the table
           contains the header for every message, with a rudimentary display of
           hierarchy - the summary shows the first message of each thread, with
           a count of messages in the thread

   debug   produce more onscreen information, and create debug output lists

An example usage would be:

   ozt ibmcom\ibmcom over kill tables

OZT would load IBMCOM.MES from the IBMCOM subdirectory below the current
directory. The file would be rethreaded, and written back over its old self.
The file IBMCOM\IBMCOM.IXM would be deleted if found, and the files
IBMCOM\IBMCOM.TBL and IBMCOM\IBMCOM.SUM would be created.


-- usage notes
   -- using as an external from OzCIS

OZT can easily be installed on the Externals menu in OzCIS. Since different
users will have different needs for this program, there is no one good way to
set things up.

You may want to run OZT on a message file after you have read new messages.
This would result in a file that only ever has two groups in it: previous
messages, and new messages directly after a pass.

__198

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- usage notes...
   -- using as an external...

You might instead only want to rethread a purge file (.PRG), or a particular
save file (.SAV).

Probably the best way to run OZT as an external would be to house it in a batch
file. That way, with one call you could run it on multiple forums, and in
different ways for each forum. Here's an (untested) sample:

   @echo off
   : rethread IBMCOM purged messages
   ozt ibmcom\ibmcom.prg over
   : rethread BPASCAL current messages
   ozt bor\bpascal over kill

   : merge and rethread IBMPRO save files
   copy /b ibmpro\ibmpro.mrg + ibmpro\ibmpro.sav ibmpro\ibmpro2.mrg
   del ibmpro\ibmpro.mrg
   ren ibmpro\ibmpro2.mrg ibmpro.mrg
   ozt ibmpro\ibmpro.mrg over


b  -- combining multiple files

OZT only works on one input file at a time. You can easily get OZT to "merge"
several files by combining them with the DOS COPY command:

   copy ibmcom.mes + ibmcom.prg + ibmcom.sav ibmcom.mrg

The previous restriction of using the /B switch for the copy command has been
removed. OZT will now remove an End-Of-File marker (Ctrl-Z) when it finds it as
the last byte in the file. However, if there is already an EOF marker embedded
within the file, OZT won't have any way of knowing about it. Such a file would
be truncated at that point anyway by the COPY command, UNLESS the /B switch was
used.

Suffice it to say that OZT will deal intelligently with an EOF marker if it is
indeed at the end of the file.


b  -- printing the thread table and summary

Both of these files are plain ASCII. The thread summary is 158 characters wide,
and the thread table is 191 characters wide (as of 1.1b). The summary will just
squeeze in on a wide carriage printer at 12 cpi, but you could easily print
both of them with a compressed pitch. If you have a narrow printer, you could
either cut out the columns you don't want to see, or ask me to create a narrow
version.


   -- using without OzCIS

It may be possible to rethread any CIS forum message capture file with OZT (ie
non-OzCIS generated), but I have not tried this. Normally when downloading
messages manually from CompuServe, they will come out in thread order anyway.
OZT could probably be used to merge multiple message downloads though.




_264

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- using debug lists

When (not if) you run across problems reading messages with OZT, there are a
few ways to go about it. First of all, to aid me in tracking down the problem,
please make a note of the exact errant behavior: error messages (runtime
errors, OZT errors, DOS errors), whether or not it hung the machine, if you
could escape with Ctrl-Break, etc. Also, it may be useful to provide an outline
of your machine, and the contents of your AUTOEXEC.BAT and CONFIG.SYS files
just in case.

Hopefully you won't have to experience this too often, but as I've mentioned
before, I'm sure we will come across variations in messages that have not been
anticipated.

Anyway, when something does go wrong, the best way to find out what happened is
to rerun OZT with the same parameters on the same file, and include the command
line switch "debug". This will cause the program to generate additional screen
info, and write extra disk files that will help to track down the error.

The additional screen info consists mainly of the thread-building recursion
process. A line is written for every message that is visited, indicating record
number in the parent index, and level of recursion. (Normally this is indicated
by a progressing row of periods. In all cases where the periods are seen, there
is one period written for every ten messages processed). The other screen
output difference generated by the "debug" switch is during writing the output
file. A series of "r"s and "w"s will be written indicating input file reads,
and output file writes. This process too is normally indicated with the row of
periods.

If the error that you are trying to pinpoint did not cause the system to
"hang", you can rerun the session "redirected" into a capture file. This will
allow looking back over the entire session in a file viewer. You may try to do
this if the error does cause a "hang", but its likely that the last portions of
the redirected output will be lost, and you won't really know when the process
stopped. (You could safely wait several minutes then reboot.)

NOTE : OZT will generate a LOT of files when the "debug" switch is used. You
may want to pull everything off into its own subdirectory just to keep the
clutter somewhat minimized. Also, none of the files are very big, but
everything grows proportionately to the size of the message file being
rethreaded, so you may want to be careful of disk space.

Here's a list of the files by order generated. All files start with the passed
in name:

   ext   contents                                                    type
   ----  ----------------------------------------------------------  ------
   .TXT  all header info from every message, in original order       text
   .UNS  the contents of parent index data structure, unsorted       text
   .IND  parent index, sorted                                        text
   .BL1  parent index, sorted, BLx for BLOCK dump)                   binary
   .DUP  parent index, duplicates marked, resorted                   text
   .BL2  same as previous                                            binary
   .VIS  parent index, "visits" field filled in                      text
   .TTB  thread table internal data structure                        text
   .TSM  thread summary internal data structure                      text
   .BL3  same as .VIS                                                binary
   .THD  thread index, sorted                                        text



_330

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- using debug lists...

Generated by the "tables" command line switch:
   .SUM  thread summary                                              text
   .TBL  thread table                                                text


In the event that you have problems reading a file and bring it to my
attention, I will be able to tell you something like:

   "Run it again with the DEBUG command line switch and...

      ...tell me what the last file generated was."
      ...look for BLAH BLAH BLAH in the XYZ file."
      ...zip up the whole lot of 'em with the original input file, and email it
      to me." (in the extreme case)


-- planned enhancements

   removal of debug features when program is stable
   reorganize documentation
   update "There are xx replies" lines
b  thread extraction feature
b  thread deleted feature


-- disclaimers
   -- testing performed

I have only tested this program on messages from the few forums that I
participate in. Needless to say, there are endless variations, within
CompuServe specifically, and within the realm of human communications in
general. You can be assured that the program performs its specified functions
given "normal" circumstances. I have spent an increasing amount of time testing
the program, and so far it runs "as planned" on the admittedly tame test files
I have generated.

The two areas most likely to cause the program to fail:

   quirky positioning of "key" characters within message text (specifically the
   "#: " message sequence starting at the beginning of a line - this happens
   when someone embeds an "example" message within there own message)

   massive message files - I've tested the program with a 500K+ file, which it
   took just fine - I presently have no idea what the maximum practical file
   size is

I hope you'll forgive my somewhat less-than-rigorous approach to this, but be
assured that as I come across problems, I will make them known, and correct
them as possible.


   -- liability

This software performs its functions, but you still use it at your own risk. I
make no warranty as to the fitness of this program for a particular purpose. I
will not be held liable for any damages arising from the use, misuse, or
inability to use this software, even if I'm aware of the possibility of such.


_396

OZT 1.1b - OzCIS Message Threader                  Copyright (C) 1993 Todd Fiske
────────────────────────────────────────────────────────────────────────────────

-- credits

OZT was inspired by Q Correll, with additional motivation from Pete Zisson, who
both have lots of messages to deal with. This fact is made true due to the use
of the #1 CompuServe navigator, OzCIS, for which we are all in the debt of
Steve Sneed.

Written with Qedit by SewWare, compiled with Turbo Pascal 6.0 by Borland, with
additional assistance from the Topaz 3.5 libraries by Software Science, and the
TPALLOC unit by TurboPower Software.


-- "ware" category, distribution

OZT is free. If you are driven to provide compensation, I will not refuse it!

Feel free to make copies of OZT to give it to friends and/or associates, but
please distribute with all files intact and unchanged: OZT.EXE, OZT.DOC, and
READ__ME.TXT.

However, please do not charge any money for it, including disk-copying costs.
For the time being, OZT is "give-a-ware".


-- contact

If you have any problems, comments, suggestions, criticism, flames, etc, I can
be reached as follows:

   Todd Fiske
   PO Box 9715-244                     CompuServe : 70451,1424
   Portland ME 04104-2000              Delphi     : TFISKE